/**
 * Work with socket connections.
 *
 * The connection class provides methods for a client to establish a
 *   network connection to a server, and for both peers to operate the
 *   connection thereafter.
 *
 * @name Connection
 * @exports Connection as api.Connection
 * @class
 */


/**
 * Start connection negotiation.
 *
 * This method starts the connection negotiation process by telling
 *     the client the protocol version that the server proposes, along
 *     with a list of security mechanisms which the client can use for
 *     authentication.
 *
 * @name Connection#start
 * @event
 * @param {Number} versionMajor The protocol major version that the server agrees to use, which
 *       cannot be higher than the client's major version.
 * @param {Number} versionMinor The protocol minor version that the server agrees to use, which
 *       cannot be higher than the client's minor version.
 * @param {Object} serverProperties This string provides a set of peer properties, used for
 * identification, debugging, and general information.
 * @param {String} mechanisms A list of the security mechanisms that the server supports, delimited
 *       by spaces.  Currently ASL supports these mechanisms: PLAIN.
 * @param {String} locales A list of the message locales that the server supports, delimited
 *       by spaces.  The locale defines the language in which the server
 *       will send reply texts.
 */

/**
 * Security mechanism challenge.
 *
 * The SASL protocol works by exchanging challenges and responses until
 *     both peers have received sufficient information to authenticate each
 *     other.  This method challenges the client to provide more information.
 *
 * @name Connection#secure
 * @event
 * @param {String} challenge Challenge information, a block of opaque binary data passed to
 *       the security mechanism.
 */

/**
 * Propose connection tuning parameters.
 *
 * This method proposes a set of connection configuration values
 *     to the client.  The client can accept and/or adjust these.
 *
 * @name Connection#tune
 * @event
 * @param {Number} channelMax The maximum total number of channels that the server allows
 *       per connection. Zero means that the server does not impose a
 *       fixed limit, but the number of allowed channels may be limited
 *       by available server resources.
 * @param {Number} frameMax The largest frame size that the server proposes for the
 *       connection. The client can negotiate a lower value.  Zero means
 *       that the server does not impose any specific limit but may reject
 *       very large frames if it cannot allocate resources for them.
 * @param {Number} heartbeat The delay, in seconds, of the connection heartbeat that the server
 *       wants.  Zero means the server does not want a heartbeat.
 */

/**
 * Signal that the connection is ready.
 *
 * This method signals to the client that the connection is ready for
 *     use.
 *
 * @name Connection#openOk
 * @event
 * @param {String} knownHosts Specifies the list of equivalent or alternative hosts that the server
 * knows about, which will normally include the current server itself.
 * Clients can cache this information and use it when reconnecting to a
 * server after a failure.
 */

/**
 * Asks the client to use a different server.
 *
 * This method redirects the client to another server, based on the
 *     requested virtual host and/or capabilities.
 *
 * @name Connection#redirect
 * @event
 * @param {String} host Specifies the server to connect to.  This is an IP address or a
 *       DNS name, optionally followed by a colon and a port number. If
 *       no port number is specified, the client should use the default
 *       port number for the protocol.
 * @param {String} knownHosts Specifies the list of equivalent or alternative hosts that the server
 * knows about, which will normally include the current server itself.
 * Clients can cache this information and use it when reconnecting to a
 * server after a failure.
 */

/**
 * Request a connection close.
 *
 * This method indicates that the sender wants to close the connection.
 *     This may be due to internal conditions (e.g. a forced shut-down) or
 *     due to an error handling a specific method, i.e. an exception.  When
 *     a close is due to an exception, the sender provides the class and
 *     method id of the method which caused the exception.
 *
 * @name Connection#close
 * @event
 * @param {Number} replyCode The reply code. The AMQ reply codes are defined in AMQ RFC 011.
 * @param {String} replyText The localised reply text.  This text can be logged as an aid to
 *   resolving issues.
 * @param {Number} classId 
 * @param {Number} methodId 
 */

/**
 * Confirm a connection close.
 *
 * This method confirms a Connection.Close method and tells the
 *     recipient that it is safe to release resources for the connection
 *     and close the socket.
 *
 * @name Connection#closeOk
 * @event
 * 
 */



/**
 * Select security mechanism and locale.
 *
 * This method selects a SASL security mechanism. ASL uses SASL
 *     (RFC2222) to negotiate authentication and encryption.
 *
 * @name Connection#startOk
 * @function
 * @param {Object} clientProperties This string provides a set of peer properties, used for
 * identification, debugging, and general information.
 * @param {String} mechanism A single security mechanisms selected by the client, which must be
 *       one of those specified by the server.
 * @param {String} response A block of opaque data passed to the security mechanism. The contents
 *       of this data are defined by the SASL security mechanism.  For the
 *       PLAIN security mechanism this is defined as a field table holding
 *       two fields, LOGIN and PASSWORD.
 * @param {String} locale A single message local selected by the client, which must be one
 *       of those specified by the server.
 */

/**
 * Security mechanism response.
 *
 * This method attempts to authenticate, passing a block of SASL data
 *     for the security mechanism at the server side.
 *
 * @name Connection#secureOk
 * @function
 * @param {String} response A block of opaque data passed to the security mechanism.  The contents
 *       of this data are defined by the SASL security mechanism.
 */

/**
 * Negotiate connection tuning parameters.
 *
 * This method sends the client's connection tuning parameters to the
 *     server. Certain fields are negotiated, others provide capability
 *     information.
 *
 * @name Connection#tuneOk
 * @function
 * @param {Number} channelMax The maximum total number of channels that the client will use
 *       per connection.  May not be higher than the value specified by
 *       the server.
 * @param {Number} frameMax The largest frame size that the client and server will use for
 *       the connection.  Zero means that the client does not impose any
 *       specific limit but may reject very large frames if it cannot
 *       allocate resources for them.  Note that the frame-max limit
 *       applies principally to content frames, where large contents
 *       can be broken into frames of arbitrary size.
 * @param {Number} heartbeat The delay, in seconds, of the connection heartbeat that the client
 *       wants. Zero means the client does not want a heartbeat.
 */

/**
 * Open connection to virtual host.
 *
 * This method opens a connection to a virtual host, which is a
 *     collection of resources, and acts to separate multiple application
 *     domains within a server.
 *
 * @name Connection#open
 * @function
 * @param {String} virtualHost Must start with a slash "/" and continue with path names
 *   separated by slashes. A path name consists of any combination
 *   of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].
 * @param {String} capabilities The client may specify a number of capability names, delimited by
 *       spaces.  The server can use this string to how to process the
 *       client's connection request.
 * @param {Boolean} insist In a configuration with multiple load-sharing servers, the server
 *       may respond to a Connection.Open method with a Connection.Redirect.
 *       The insist option tells the server that the client is insisting on
 *       a connection to the specified server.
 */

/**
 * Request a connection close.
 *
 * This method indicates that the sender wants to close the connection.
 *     This may be due to internal conditions (e.g. a forced shut-down) or
 *     due to an error handling a specific method, i.e. an exception.  When
 *     a close is due to an exception, the sender provides the class and
 *     method id of the method which caused the exception.
 *
 * @name Connection#close
 * @function
 * @param {Number} replyCode The reply code. The AMQ reply codes are defined in AMQ RFC 011.
 * @param {String} replyText The localised reply text.  This text can be logged as an aid to
 *   resolving issues.
 * @param {Number} classId 
 * @param {Number} methodId 
 */

/**
 * Confirm a connection close.
 *
 * This method confirms a Connection.Close method and tells the
 *     recipient that it is safe to release resources for the connection
 *     and close the socket.
 *
 * @name Connection#closeOk
 * @function
 * 
 */

